Add OAuth-protected MCP support for standalone Hyperforge by arnaugrispg · Pull Request #61 · nuclia/hyperforge

arnaugrispg · 2026-07-09T12:33:24Z

Description

Adds optional OAuth configuration for standalone Hyperforge MCP endpoints.

When configured, Hyperforge now:

Exposes OAuth protected resource metadata for MCP clients.
Returns 401 with the proper resource metadata reference when MCP requests are missing or have invalid bearer tokens.
Validates incoming JWT bearer tokens using the configured JWKS URL before allowing MCP traffic through.
Requires token expiration (exp) and rejects tokens when JWKS validation fails.
Optionally forwards the validated Authorization header to the inner MCP/service backend, enabling use cases like MarkLogic OAuth passthrough.

Includes focused standalone MCP auth tests covering metadata exposure, unauthorized requests, valid token passthrough, missing exp, and JWKS failure handling.

Copilot

Pull request overview

Adds optional OAuth/JWT-based protection for standalone Hyperforge MCP endpoints, including protected-resource metadata discovery and bearer token validation against a configured JWKS, with tests validating expected 401/200 behaviors and optional Authorization passthrough.

Changes:

Introduces standalone OAuth/JWT validation (JWKS fetch/cache, JWT signature + claims + scope checks) and wires it into standalone auth middleware for MCP routes.
Adds per-agent mcp_auth configuration and uses it to emit RFC9728 protected-resource metadata and control Authorization header forwarding.
Adds standalone test coverage for protected vs open MCP behavior, metadata exposure, JWT failures, and Authorization passthrough control.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
hyperforge/tests/standalone/test_mcp_auth.py	Adds standalone MCP OAuth/authn test suite (metadata, 401s, JWT validation, header passthrough).
hyperforge/src/hyperforge/standalone/oauth.py	Implements JWKS caching and JWT bearer validation (signature/claims/scopes).
hyperforge/src/hyperforge/standalone/config.py	Adds `StandaloneMCPAuthConfig` and `mcp_auth` per-agent configuration.
hyperforge/src/hyperforge/standalone/app.py	Replaces open auth backend with standalone backend that enforces MCP OAuth when configured + emits proper 401 metadata.
hyperforge/src/hyperforge/api/v1/mcp_interaction.py	Adds protected-resource metadata endpoint config override and optional Authorization forwarding control into interaction headers.
hyperforge/src/hyperforge/api/v1/interaction.py	Updates `ensure_session_exists` to return effective session id + error tuple; updates websocket call site.
hyperforge/src/hyperforge/api/session.py	Adds UUID pre-check to `session_exists` before calling NucliaDB by id.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

carlesonielfa

1 comment

carlesonielfa · 2026-07-10T08:30:27Z

+    auth_config = get_enabled_mcp_auth(getattr(app, "_agents_cfg", {}), agent_id)
+    resource = (
+        auth_config.protected_resource
+        if auth_config is not None and auth_config.protected_resource is not None
+        else str(mcp_url.replace(scheme="https"))
+    )
+    fallback_authorization_server = getattr(app.settings, "hydra_public_url", None)
+    authorization_servers = (
+        [auth_config.authorization_server]
+        if auth_config is not None and auth_config.authorization_server is not None
+        else (
+            [fallback_authorization_server]
+            if fallback_authorization_server is not None
+            else []
+        )
+    )
+    scopes_supported = (
+        auth_config.scopes_supported
+        if auth_config is not None
+        else getattr(app.settings, "hydra_scopes_supported", [])
+    )
    return {
-        "resource": mcp_url_https,
-        "scopes_supported": app.settings.hydra_scopes_supported,
-        "authorization_servers": [app.settings.hydra_public_url],
+        "resource": resource,
+        "scopes_supported": scopes_supported,
+        "authorization_servers": authorization_servers,


any reason to be using getattr instead of accessing the fields normally? getattr bypasses type checking and might be a source for errors

I used getattr to avoid conflicts between standalone and non-standalone settings, but I agree it’s better not to use it here, so I replaced it with a dedicated helper and removed the getattr usage.

carlesonielfa · 2026-07-10T08:35:19Z

+        missing = [
+            field
+            for field in ("authorization_server", "jwks_url")
+            if getattr(self, field) is None


another getattr here

bloodbare · 2026-07-10T09:31:15Z

+    app: "HTTPApplication", agent_id: str, headers: Headers
+) -> dict[str, str]:
+    interaction_headers = dict(headers.items())
+    auth_config = get_enabled_mcp_auth(getattr(app, "_agents_cfg", {}), agent_id)


Why a getattr to check it ? could be less hacky ?

bloodbare · 2026-07-10T09:31:38Z

+    auth_config = get_enabled_mcp_auth(getattr(app, "_agents_cfg", {}), agent_id)
+
+    authorization = headers.get("authorization")
+    if auth_config is not None and not auth_config.forward_authorization_header:


Which use case covers this condition?

This condition was added to support using the token only for MCP auth, but this MCP will never have auth on its own, so I’m removing this use case.

bloodbare · 2026-07-10T09:32:00Z

+        if auth_config is not None and auth_config.protected_resource is not None
+        else str(mcp_url.replace(scheme="https"))
+    )
+    fallback_authorization_server = getattr(app.settings, "hydra_public_url", None)


bloodbare · 2026-07-10T09:32:15Z

+    scopes_supported = (
+        auth_config.scopes_supported
+        if auth_config is not None
+        else getattr(app.settings, "hydra_scopes_supported", [])


Add OAuth-protected MCP support for standalone Hyperforge

95e2fa4

arnaugrispg requested a review from a team July 9, 2026 12:33

Fix test

242b9ea

arnaugrispg requested a review from Copilot July 9, 2026 12:53

Copilot started reviewing on behalf of arnaugrispg July 9, 2026 12:54 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Comment thread hyperforge/src/hyperforge/standalone/oauth.py Outdated

Potential fix for pull request finding

911e91b

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

arnaugrispg requested a review from Copilot July 9, 2026 13:33

Copilot started reviewing on behalf of arnaugrispg July 9, 2026 13:34 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Comment thread hyperforge/src/hyperforge/api/v1/mcp_interaction.py

Comment thread hyperforge/src/hyperforge/standalone/oauth.py

Comment thread hyperforge/src/hyperforge/api/v1/interaction.py

Fix copilot

7ac5b68

arnaugrispg requested a review from Copilot July 9, 2026 13:52

Copilot started reviewing on behalf of arnaugrispg July 9, 2026 13:52 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Comment thread hyperforge/src/hyperforge/standalone/oauth.py

Comment thread hyperforge/src/hyperforge/standalone/config.py Outdated

Comment thread hyperforge/src/hyperforge/api/v1/mcp_interaction.py

Fix copilot

fb3ba28

arnaugrispg requested a review from Copilot July 9, 2026 14:13

Copilot started reviewing on behalf of arnaugrispg July 9, 2026 14:14 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Comment thread hyperforge/src/hyperforge/standalone/app.py

Comment thread hyperforge/tests/standalone/test_mcp_auth.py Outdated

Fix copilot

37b5d5f

arnaugrispg requested a review from Copilot July 9, 2026 14:39

Copilot started reviewing on behalf of arnaugrispg July 9, 2026 14:40 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Comment thread hyperforge/src/hyperforge/api/session.py Outdated

Comment thread hyperforge/tests/standalone/test_mcp_auth.py Outdated

arnaugrispg and others added 2 commits July 9, 2026 16:55

Potential fix for pull request finding

56c35d9

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

532fb40

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

arnaugrispg requested a review from Copilot July 9, 2026 14:55

Copilot started reviewing on behalf of arnaugrispg July 9, 2026 14:56 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Comment thread hyperforge/src/hyperforge/standalone/oauth.py

Potential fix for pull request finding

61bcf1f

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

carlesonielfa reviewed Jul 10, 2026

View reviewed changes

bloodbare reviewed Jul 10, 2026

View reviewed changes

arnaugrispg added 3 commits July 10, 2026 15:09

Fix comments

1f052ea

Simplify agents config

4ecd94c

Fix test

15d4fb7

Uh oh!

Conversation

arnaugrispg commented Jul 9, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

carlesonielfa left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants